Release 10.1A: OpenEdge Reporting:
Report Builder Deployment

Complete descriptions of each predefined parameter

This section describes each of the predefined Report Engine parameters in alphabetical order.

RB-BEGIN-PAGE

Specifies the starting page number for the report. The value you specify for RB-BEGIN-PAGE must be less than or equal to the report’s ending page, which can be saved in the report definition or specified by RB-END-PAGE. The default value of RB-BEGIN-PAGE is 0, which means to use the beginning page saved in the report definition. The default beginning page value saved in a report definition is 1.

For example, a user can restart a cancelled report where it was interrupted by specifying the starting page number as the RB-BEGIN-PAGE value and 999999999 as the RB-END-PAGE value.

To reprint one or more consecutive pages of a report, specify the page numbers in the RB-BEGIN-PAGE and RB-END-PAGE parameters. To print just one page, specify the same page number for both parameters.

RB-DB-CONNECTION

Allows you to override the saved database connections by specifying the logical name of the database as saved in the report and all connection parameters Report Engine needs to connect to the database containing the report data. You can specify a string composed of any valid Progress 4GL connection parameters.

Report Builder saves all required database connection information with the report definition (except the password). You need to specify a value for RB-DB-CONNECTION only in three situations:

If you want to run a report using a database other than the one saved with the report definition.
If you want to run a report using the same database that is saved with the report definition, but you are connecting to that database on the command line that invokes Report Engine (or in a .pf file that Report Engine reads on startup).
If your database requires a password, and you do not want Report Engine to prompt you for it.

Use the logical database name, not the physical database name, when specifying which report databases are to be overridden with the RB-DB-CONNECTION parameter.

If you have security measures such as passwords and user IDs enabled, you must specify the Password (-P) and User ID (-U) parameters or the Report Password (-rbP) parameter if you are using the table interface.

RB-DB-CONNECTION and the Report Engine table interface

When you use the Report Engine table interface, you can use RB-DB-CONNECTION in two ways:

Specify all the database connection information. To do this, simply specify the database connection information using the Progress 4GL connection parameters.
Specify to use a database to which Report Engine was connected by the command line. To do this, you must specify a complete database connection for the report on the command line or in the rbstart.pf file, then specify the RB-DB CONNECTION values. See Chapter 4, "Report Engine Table Interface," for information about using and invoking the table interface, including using the rbstart.pf file.

You use two symbols to indicate different types of database connection overrides: => and =. The => symbol indicates to use a database already connected on the command line. The = symbol indicates to establish a new database connection and ignore any databases connected on the command line. The => override can be used only with the table interface.

When you use these symbols to specify the database connection information, follow these rules:

On the left side of both symbols (=> and =), specify the logical name of a database saved with the report.
On the right side of the => symbol, specify the logical name of a database that was connected on the command line.
On the right side of the = symbol, specify a complete connection string.

To override a connection to an OpenEdge database saved in the report definition with a connection to a non-OpenEdge database, you must specify two connections. The first connection is to the OpenEdge schema holder and the second is to the non-OpenEdge database. Because you must use two connections, you cannot simply use the = symbol in the RB-DB-CONNECTION parameter. Instead, you must connect to the schema holder and non-OpenEdge database on the command line and then use the => symbol in the RB-DB-CONNECTION parameter to override the database used in the report with the non-OpenEdge database. This can only be done with the table interface.

Note: If you put the Report Engine table into the same database as your application data, and if you create a report that refers to that database, you must use the RB-DB-CONNECTION parameter with the => symbol. If you do not, Report Engine might indicate that the database is already connected when it tries to run the report.

The problem is that because the Report Engine table information is in the database, you must specify the database connection information on the command line that invokes Report Engine (or in a .pf file that Report Engine reads on startup). This means that Report Engine will already be connected to the database by the time it starts working on the report; when it tries to connect to the database requested in the report, it will be attempting to connect to the same database a second time.

Sometimes, Report Engine considers this an error; however, even if it does not, this second connection can slow down your database server. To avoid this, when you run this report, you must specify a value for RB-DB-CONNECTION that tells Report Engine to reuse the connection it has already made, rather than trying to establish a new connection for the report.

The RB-DB-CONNECTION value looks something like this:

logical1 => logical2

Note that logical1 is the logical name of the database as stored in the report and logical2 is the logical name used for the same database in the connection parameters on the command line. In this situation, where the Report Engine database is the same as the application database, these two logical names are often the same.

The following example shows how to override the stored connection information. If the report definition specifies the physical database as newdb1.db and the logical database name as newdb1, you override the saved database with a connection established on the command line with the following steps:

Override the saved database connection information using the following value in the RB-DB-CONNECTION parameter:

newdb1 => newdb2

The => symbol indicates to use a database already connected on the command line. This parameter value means that when Report Engine runs the report, it uses the connection established on the command line and does not attempt to make a connection to the newdb1 database.

Invoke Report Engine with the following command:

RUN aderb/_prore.p(false, "-db newdb2 -1 -rbtable Rep-Eng")

This command invokes Report Engine with a connection to the newdb2 database. In this example, the newdb2 database contains both the tables required by the report and the table (Rep-Eng) that specifies the RB-DB-CONNECTION parameter value.

Instead of specifying the connection on the command line, you could have used the following value in the RB-DB-CONNECTION parameter in the Rep-Eng table:

newdb1 = -db newdb3 -1

The = symbol indicates to establish a new database connection using the specified connection information and ignore the databases connected on the command line. This value means that when you invoke Report Engine, it will override the stored database connection information for newdb1 with the information -db newdb3 -1.

You can override the database connection information for multiple databases using the RB-DB-CONNECTION parameter. To override multiple databases in the same RB-DB-CONNECTION parameter value, separate each section with a new-line character (~n) as shown in the following example:

sample => newdb2~ndemo = -db newdb3 -1~nsports = -db newdb4 -1

This example overrides the connection information for three report databases (with logical names sample, demo, and sports). Notice that each database override is separated by a new-line character (~n). When entering data into an OpenEdge fill-in field, you must use CHR(10) to identify the new-line character.

When you are overriding database connection information for a report that uses multiple databases, you do not have to provide override information for all the databases; only the ones that you want to override.

There are several reasons to use the table interface with RB-DB-CONNECTION:

You can specify overrides for more than one database.
You can use the RB-DB-CONNECTION parameter to reference a database connected on the command line, rather than hard-coding the connect string in the RB-DB-CONNECTION parameter.
If all the reports are run against the same database, you can connect to it on the command line, and then Report Engine maintains that one database connection for all reports instead of reestablishing the connection as it runs each report.

RB-DB-CONNECTION and the Report Engine PRINTRB and PRNTRB2 interfaces

When you use the PRINTRB or PRNTRB2 interfaces to the Report Engine, the RB-DB-CONNECTION parameter allows you to override only one database.

If you specify the RB-DB-CONNECTION parameter as “orders=-db c:\mydata\orders -1", where the leading “orders=” indications the logical name of the database as specified in the report definition, Report Engine discards all the connection information saved in the report definition and uses only the newly specified database connection parameters.

With the PRINTRB or PRNTRB2 interfaces, you cannot use the => symbol. However, you can use only the = symbol. The = symbol indicates to establish a new database connection using the specified connection information.

When you use the = symbol to specify the database connection information, follow these rules:

On the left side of the = symbol, specify the logical name of the database saved with the report.
On the right side of the = symbol, specify a complete connection string.

For example, if the report definition specifies the physical database as newdb1.db and the logical database name as newdb1, you use the RB-DB-CONNECTION parameter to override the connection information using the following value:

newdb1 = -db newdb3 -1

This value means that when you invoke Report Engine, it will override all the stored database connection information for newdb1 with the information -db newdb3 -1. The = symbol indicates to establish a new database connection using the specified connection information.

For backward compatibility, you can still use the syntax required by earlier versions of Report Builder to override individual parameters. For example, the following value tells Report Engine to simply add the values to the existing connection information stored in the report:

-db newdb3 -S newserver

RB-DISPLAY-ERRORS

Controls whether Report Engine displays an error message dialog box when it encounters an error.

If the parameter is false and you are using the PRINTRB and/or PRNTRB2 interfaces, Report Engine does not display the error messages, but writes them to the report status file in the current working directory. However, if you are using the table interface, Report Engine writes to the report status file only if you use the Report Status File (-rbstatfile) parameter. The report status file is a text file to which Report Engine writes status and error information. See the "Verifying report status" section for information about the status file.

If the parameter is true, Report Engine displays the error message on the screen in addition to possibly writing it to the report status file. When Report Engine displays the error message dialog box, the user must choose OK to acknowledge the error. Report Engine then either terminates processing of that report or displays a dialog box where the user can enter the correct information.

RB-DISPLAY-STATUS

Controls whether Report Engine displays a Print Status window while it generates a report.

If the parameter is false, Report Engine does not display a Status window, but displays as an icon while it is running.

If the parameter is true, Report Engine displays a Status window.

RB-END-PAGE

Specifies the ending page number for the report. The default value for this parameter is 0, which means to use the ending page saved in the report definition. The default ending page saved in the report definition is 999999999. The value you specify for RB-END-PAGE must be greater than or equal to the report’s beginning page, which can be either saved in the report definition or specified using RB-BEGIN-PAGE.

For example, to print only the first ten pages of a long report, specify RB-BEGIN-PAGE as 1 and RB-END-PAGE as 10.

To reprint one or more consecutive pages of a report, specify the page numbers in the RB-BEGIN-PAGE and RB-END-PAGE parameters. To print just one page, specify the same page number for both parameters.

RB-FILTER

Specifies a logical expression to override the filter saved in the report definition, if any, when RB-INCLUDE-RECORDS is set to override ("O").

The syntax of the RB-FILTER expression is identical to that of any calculated field expression that returns a logical value. The RB-FILTER expression can be up to 1024 characters long. When an expression is specified, Report Engine selects all records where the value of the RB-FILTER expression is true. The expression can reference any data, aggregate fields, or calculated fields that are available in the report.

If the expression you enter is not server-evaluatable, the report might run significantly slower. For example, if you enter the filter expression City = "Dallas", Report Engine selects all records where the value in the City field is Dallas. If the city name were in a character field named City-Note, the following filter expression selects all records in which the City-Note field begins with the word "Dallas":

"City-Note MATCHES ~"Dallas*~""

You must enclose literal strings in quotation marks and use the tilde-quote (~"string~") or quote-quote (""string"") around the embedded character strings.

Entering “Balance >= 200” selects all records where the value in the Balance field is greater than or equal to 200. To select records where the date in the Order-Date field of the Order table is January 31, 2003, use this format:

"Order.Order-Date = 01/31/03"

If the same field name exists in more than one table used in your report, you must specify the table alias and the field name as shown in the previous example.

You can enter compound filter expressions by using parentheses. For example, the following filter expression selects all records where the value in the City field is either Dallas or Houston and where the value in the Credit-Limit field is greater than 50,000:

"(City = ""Dallas"" OR City = ""Houston"") AND Credit-Limit > 50000"

Note: You must set RB-INCLUDE-RECORDS to override ("O") for the RB-FILTER to override the filter in the report definition.

RB-INCLUDE-RECORDS

Controls whether to apply a filter to the report at run time. Table 3–2 lists the valid RB-INCLUDE-RECORDS values.

Table 3–2: RB-INCLUDE-RECORDS values 

Value	Meaning
S	(Saved) runs the report using the filter saved in the report definition, if any. Report Engine ignores the expression in RB-FILTER and runs the report as specified in the report definition.
E	(Entire) runs the entire report, ignoring any filter specified in the report definition or in the RB-FILTER parameter.
O	(Override) overrides the filter specified in the report definition with the expression in the RB-FILTER parameter.
?	(Question mark) displays a dialog box allowing the user to enter a filter expression or edit the filter specified in the report definition.
blank	Runs the report using the filter saved in the report definition, if any. Report Engine ignores the expression in RB-FILTER and runs the report as specified in the report definition.

When you use the question mark (?) value for the RB-INCLUDE-RECORDS parameter, Report Engine ignores the value of RB-FILTER.

RB-MEMO-FILE

Contains the name and optional directory location of a memo file to be used in place of the one saved in the report definition. The override memo file must be on the machine where Report Engine is running. Report Engine searches for the memo file in the following ways:

If you specify a . . .	Then Report Engine searches . . .
Directory and a filename	Only for the specified directory and file.
Directory without a filename	The specified directory for the memo file name saved in the report definition.
File name without a directory	For a file with the specified name in the directory saved in the report definition.

If you leave this parameter blank, Report Engine uses the memo file specified in the report definition.

RB-NO-WAIT

Specifies whether to use synchronous or asynchronous processing when you are using the PRINTRB or PRNTRB2 interfaces. If this parameter is “No”, then aderb/_printrb.p does not return until Report Engine finishes printing the report. If it is “Yes”, then aderb/_printrb.p returns as soon as Report Engine starts, allowing the 4GL program to continue with other tasks while the report prints.

RB-NO-WAIT is required only with the PRINTRB and PRNTRB2 interfaces. In order to run multiple instances of Report Engine with PRNTRB2, RB-NO-WAIT must be set to “Yes.” You cannot use this parameter if you are using the table interface. Instead, you specify this functionality as an argument to _prore.p. See Chapter 4, "Report Engine Table Interface," for more information.

RB-NUMBER-COPIES

Specifies the number of copies of the report you want to print. The number must be between 0 and 999, inclusive. If you enter 0, Report Engine prints the number of copies specified in the report definition. If you specify a number, the specified value overrides the number entered in the Report Builder Print Setup dialog box.

RB-OUTPUT-FILE

Saves report output as a file for printing later, or use it in conjunction with RB-PRINT-DESTINATION to export a report to a text file without printer control codes. The name of the output file can include a path. The override output file must be on the machine where Report Engine is running.

For example, to send a report to a text file Order.txt in the c:\projects\text subdirectory, specify the following value for the RB-OUTPUT-FILE parameter, and RB-PRINT-DESTINATION as “A”:

c:\projects\text\Order.txt

If RB-OUTPUT-FILE does not include a path, Report Engine places the file in the current working directory.

When you specify this parameter, and if RB-PRINT-DESTINATION contains the value A, the report outputs as a text file. If the value of RB-PRINT-DESTINATION is anything other than A, Report Engine outputs the report to a file with printer control codes.

If RB-OUTPUT-FILE does not include a path, Report Engine places the file in the current working directory.

RB-PRINT-DESTINATION

Specifies to print the report on the printer specified in the report definition or with the RB-PRINTER-NAME parameter or to display the report on the screen. Leave the parameter blank to print to the printer saved in the report definition or to the printer specified as the RB-PRINTER-NAME value.

Table 3–3 describes the valid RB-PRINT-DESTINATION values.

Table 3–3: RB-PRINT-DESTINATION values 

Value	Meaning
D	Displays the report on the screen. This allows the user to preview the report before printing it. After previewing the report, the user can choose Print on the Preview screen to send the report to the printer specified in the report definition or specified as the RB-PRINTER-NAME value. If the value of RB-PRINT-DESTINATION is D and you specify RB-OUTPUT-FILE, when the user chooses Print in Preview, Report Engine outputs the report to the file specified in RB-OUTPUT-FILE, using control codes for the printer specified with RB-PRINTER-NAME.
A	Sends the report to the text file named as the RB-OUTPUT-FILE value. Report Engine exports the report as a text file without printer control codes.
?	Allows the user to select the print destination (screen or printer) at run time. When the value of RB-PRINTER-NAME is a question mark, Report Engine prompts the user to also choose the printer at run time. If you specify RB-WINDOW-TITLE, the dialog box title bar contains the RB-WINDOW-TITLE value. If RB-WINDOW-TITLE is empty, the title bar displays the report name.
blank	Sends the report directly to the printer specified in the report definition or specified by RB-PRINTER-NAME, or if RB-OUTPUT-FILE is specified to that file. Report Engine includes the printer control codes in the output file for the specified printer, or if no printer is specified, for the saved printer.

RB-PRINTER-NAME

Specifies the printer on which to print the report. You can specify:

The name of an available Windows printer (for example, “HP LaserJet Series III”). In Report Builder choose Report Print Setup to access the Printer Setup dialog box. This dialog box lists the available Windows printers.
A question mark (?) to allow the user to select a printer at run time. When RB-PRINTER-NAME contains a question mark, the Printer Setup dialog box appears.
A blank value to use the printer saved in the report definition.

Regardless of which value is specified, the printer must be a printer that is available to the machine where Report Engine is running.

When you specify a question mark (?), the Printer Setup option in the Windows Control Panel controls which printers appear in the Printer Setup dialog box. The selected printer is always the printer specified in the report definition. The user can select another printer and port or choose the Setup button to change other print characteristics.

You cannot override the paper tray selection with the Report Engine parameters. You can change the paper tray selection only when running a report. However, if you specify a tray (upper or lower) and use a printer that has only a single tray, Report Engine runs the reports correctly.

RB-PRINTER-PORT

Specifies the printer port. You can:

Specify a port, such as “LPT1:”. You must include the colon (:).
Enter a question mark (?) value. When RB-PRINTER-PORT contains a question mark, the user sees the Printer Setup dialog box.
Specify a blank value to use the printer port saved in the report definition.

Regardless of which value is specified, the port must be on the machine where Report Engine is running.

RB-REPORT-LIBRARY

Identifies the library that contains the report. The library name can include a path. If you do not include a path, Report Engine searches for the library in the default directory specified in the registry or the progress.ini file. If you have not specified a default library directory, Report Engine searches for the library in the current working directory. The .prl extension is optional. The report library must be accessible from the machine on which Report Engine is running.

Note: You must specify the library name. If you leave this parameter blank or if the library you specify cannot be found or read, Report Engine writes an error in the status file or RB-STATUS field, depending on the interface or optional command-line parameters you are using. Regardless of which interface you use, if you enable RB-DISPLAY-ERRORS, Report Engine displays an error message box.

For example, a value of c:\projects\reports identifies the report library as reports.prl in the subdirectory projects on drive C.

RB-REPORT-NAME

Specifies the report name.

For example, to run a report named Discount Order, enter "Discount Order" as the value for this parameter. The report you specify must be in the library specified by RB-REPORT-LIBRARY.

Note: You must specify the report name. If you leave this parameter blank or if the report does not exist in the library you specify, Report Engine writes an error in the status file or RB-STATUS field, depending on the interface or optional command-line parameters you are using. Regardless of which interface you use, if you enable RB-DISPLAY-ERRORS, Report Engine displays an error message box.

RB-STATUS

Specifies the status of the report generation for the table interface. If you specify the Report Update (-rbupds) parameter when you invoke Report Engine, Report Engine updates the RB-STATUS field with information describing where it is in the report generation process. Table 3–4 describes the possible parameter values.

Table 3–4: RB-STATUS values 

Value	Meaning
STARTED	Report Engine has started generating the report.
COMPLETED	Report Engine has finished generating the report. This does not mean the report has been printed.
ERROR: message	Report Engine has detected an error and cannot complete generating the report.
blank	The Report Update (-rbupds) parameter is not set or Report Engine has not yet started generating this report.
CANCELLED	The user selected to cancel the report.

For example, if you specify -rbupds when you invoke Report Engine, when Report Engine starts generating the report, it sets the value of the RB-STATUS field to “STARTED.”

You optionally use RB-STATUS when you use the table interface. You cannot use this parameter with the PRINTRB interface.

RB-STATUS-FILE

Specifies the filename of the report status file into which Report Engine will write the status information.

This parameter tells Report Engine to create a file containing information about the report it has generated. This file is called the report status file. If the file does not exist, Report Engine creates one. If the file does exist, Report Engine overwrites it. If you do not specify a filename, Report Engine does not generate a status file. If you do not specify the full pathname, Report Engine uses its current working directory.

For example, to create a status file status.txt in the c:\work\status subdirectory, specify the following value for the RB-STATUS-FILE parameter:

c:\work\status\status.txt

RB-TAG

Specifies a tag that determines whether to generate a report, based on the value from the Report Tag (-rbtag) parameter, when you use the table interface. When Report Engine generates the reports for which you have specified report parameters in the table, it generates only those whose values in this parameter match the -rbtag parameter value.

If you do not specify a -rbtag value, Report Engine runs all the reports in the Report Engine table, regardless of the value in the RB-TAG field.

For example, if the Report Engine table contains report records for four different quarterly reports, you can assign each set of records for a quarter a different RB-TAG value such as Q1, Q2, Q3, and Q4. Then when you invoke Report Engine, specify the desired tag with the -rbtag parameter. For example, to run the reports for the first quarter, you specify Q1 as the -rbtag value:

RUN aderb\_prore.p(false, "-db sample.db -1 -rbtable Rep-Eng -rbtag Q1")

Another way to use this parameter is to store the reports for multiple users in the Report Engine table, then specify a specific user’s tag to run only his or her reports.

You optionally use RB-TAG when you use the table interface. You cannot use this parameter with the PRINTRB or PRNTRB2 interfaces.

RB-TEST-PATTERN

Controls whether Report Engine allows the user to print a test pattern. A test pattern is useful for aligning forms or labels in the printer.

The test pattern flag can be either true or false. True means to display a prompt before printing the report to allow the user the option of printing a test pattern. False means do not display this prompt.

If the parameter is false, Report Engine does not offer a choice to print a test pattern.

If the parameter is true, Report Engine prompts the user to select whether to print the test pattern before printing the report. The user can print the test pattern as many times as necessary and then print the report.

RB-WINDOW-TITLE

Displays the specified title in the following places:

The title bar of the Preview window.
The Print Status window (if RB-DISPLAY-STATUS = True).
Below the Runtime icon (if RB-DISPLAY-STATUS = False).
The title bar of the dialog box that displays when RB-PRINT-DESTINATION = ?

By default, Report Engine displays the report name in these places. You can enter up to 31 characters for the window title.